package sjtu.rfid.rri.services.io;

import java.io.IOException;

/**
 * This interface defines a connection consumer which can listen on some
 * connection and notify the specified MessageListener's onMessage() method.
 * 
 * @author jinghao
 * 
 */
public interface Consumer {

	// consumer status
	int UNSTARTED = 0, ACTIVE = 1, PAUSED = 2, CLOSED = 3;

	/**
	 * start the consumer. This method has no effect if consumer is not in
	 * UNSTARTED status.
	 * 
	 */
	void start();

	/**
	 * close the consumer and close the connection. This method has no effect if
	 * consumer is not in ACTIVE or PAUSED status. Be caution: This method will
	 * close the input stream!
	 * 
	 */
	void close() throws IOException;

	/**
	 * pause the consumer if it is active and it has no effect if consumer is
	 * not active.
	 * 
	 */
	void pause();

	/**
	 * activate the consumer from paused state and it has no effect if consumer
	 * is not paused.
	 * 
	 */
	void activate();

	/**
	 * Adds a MessageListener to the set of MessageListeners for this consumer,
	 * provided that it is not the same as some messageListener already in the
	 * set. The order in which notifications will be delivered to multiple
	 * messageListeners is in the order of adding in.
	 * 
	 * @param messageListener
	 *            the MessageListener to be added.
	 * @throws NullPointerException
	 *             if the parameter messageListener is null.
	 */
	public void addMessageListener(MessageListener messageListener);

	/**
	 * Removes a MessageListener from the set of MessageListeners of this
	 * consumer. Passing <CODE>null</CODE> to this method will have no effect.
	 * 
	 * @param messageListener
	 *            the messageListener to be removed.
	 */
	public void removeMessageListener(MessageListener messageListener);

}
